Skip to main content

Bring your own domain

Subscription required

Custom domains are available on subscribed (Basic/Pro) plans only. Anonymous tunnels and free/unsubscribed accounts cannot use custom domains or CNAMEs.

Each tunnel gets an assigned FQDN based on your tunnel ID (e.g., <tunnel-id>.tun.cruma.io). To use your own domain, add a CNAME and include that hostname in a frontend route.

Add the CNAME​

Create a CNAME in your DNS provider pointing to the tunnel FQDN:

app.yourdomain.com CNAME <tunnel-id>.tun.cruma.io.

Use it in a config file​

Add the custom hostname as a frontend that references your backend:

tunnel_id: "demo-tunnel"
tunnel_secret: "beta-secret-123"

backends:
  - id: web
    kind: http
    destination: "127.0.0.1:3000"

frontends:
  - hostname: "react-dev"
    backend_id: web
  - hostname: "app.yourdomain.com"
    backend_id: web

Run it:

cruma start ./cruma.yaml

Or add it to an existing config via CLI:

cruma config add http 127.0.0.1:3000 --hostname app.yourdomain.com

Multiple frontends can point to the same backend — here both the shortname (react-dev, which expands to react-dev.<tunnel-id>.tun.cruma.io) and the custom domain (app.yourdomain.com) route to the same service.

Wildcard hostnames​

You can also use wildcard patterns for custom domains:

frontends:
  - hostname: "*.yourdomain.com"
    backend_id: web

This requires a wildcard CNAME (or individual CNAMEs for each subdomain) pointing to your tunnel FQDN.

TLS for custom hostnames​

Once DNS propagates, your custom hostname will resolve through the tunnel just like the assigned address.

TLS for custom hostnames is terminated on your agent, not on Cruma's servers. The agent automatically obtains a trusted certificate from Let's Encrypt via ACME TLS-ALPN-01 — no manual certificate setup is needed. This means payloads are encrypted end-to-end between the client and your agent; Cruma infrastructure only forwards the encrypted TLS stream.

Assigned Cruma hostnames (*.tun.cruma.io and *.*.tun.cruma.io) now have two modes:

  • On paid plans with an active subscription, the agent attempts to obtain a certificate for its assigned hostname via ACME DNS-01. Once that certificate is ready, the agent can terminate TLS for the assigned hostname too.
  • If the agent cannot get the certificate yet, TLS falls back to the Cruma ingress using Cruma-managed certificates.

You can see the current assigned-hostname certificate status in the GUI on the Certificates page.

For additional hardening, you can set CAA records on your domain to restrict certificate issuance and consider pinning or mTLS. See Security & TLS for details.